Linux Cubed Series 2: Applications

home *** CD-ROM | disk | FTP | other *** search

/ Linux Cubed Series 2: Applications / Linux Cubed Series 2 - Applications.iso / editors / emacs / xemacs / xemacs-1.006 / xemacs-1 / lib / xemacs-19.13 / info / hyperbole.info-1 < prev next >

Wrap

GNU Info File | 1995-09-01 | 47.2 KB | 1,154 lines

This is Info file ../info/hyperbole.info, produced by Makeinfo-1.63 from the input file hyperbole.texi. File: hyperbole.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) Preface ******* Copyright (C) 1991-1995 Free Software Foundation, Inc. All trademarks referenced herein are trademarks of their respective holders. This edition of the Hyperbole User Manual is for use with any version 3.19.07 or greater of Hyperbole. Hyperbole is available for free use, distribution, and modification under the terms of version 2 or later of the GNU Public License (GPL). No representations are made about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. Hyperbole was designed and written by Bob Weiner. Motorola, Inc. funded and donated this work for free redistribution as part of the InfoDock integrated productivity toolset. Hyperbole and InfoDock can be obtained via anonymous ftp on the Internet from: `/anonymous@cs.uiuc.edu:/pub/xemacs/infodock'. This manual explains user operation and summarizes basic developer facilities of Hyperbole. This major release of Hyperbole concentrates on providing convenient access to information and control over its display. The next major release, version 4, will emphasize flexible views and structure manipulation within bodies of information. (Structure manipulation (outlining) is included within this release but a number of useful functions and additional documentation remain to be written.) Hyperbole is an open, efficient, programmable information management and hypertext system. It is intended for everyday work on any UNIX platform supported by GNU Emacs. It works well with the versions of Emacs that support multiple X or NEXTSTEP windows: Emacs 19, XEmacs (formerly called Lucid Emacs) and Epoch. Hyperbole allows hypertext buttons to be embedded within unstructured and structured files, mail messages and news articles. It offers intuitive mouse-based control of information display within multiple windows. It also provides point-and-click access to Info manuals, ftp archives, Wide-Area Information Servers (WAIS), and the World-Wide Web (WWW) hypertext system through encapsulations of software that support these protocols. Hyperbole consists of four parts: 1. an interactive information management interface, including a powerful rolodex, which anyone can use. It is easy to pick up and use since it introduces only a few new mechanisms and provides user-level facilities through a menu interface, which you control from the keyboard or the mouse; 2. an outliner with multi-level autonumbering and permanent ids attached to each outline node for use as hypertext link anchors; 3. a set of hyper-button types that provides core hypertext and other behaviors. Users can make simple changes to button types and those familiar with Emacs Lisp can quickly prototype and deliver new types; 4. a set of programming library classes for system developers who want to integrate Hyperbole with another user interface or as a back-end to a distinct system. (All of Hyperbole is written in Emacs Lisp for ease of modification. Although Hyperbole was initially designed as a prototype, it has been engineered for real-world usage and is well structured.) Hyperbole may be used simply for browsing through documents pre-configured with Hyperbole buttons, in which case, one can safely ignore most of the information in this manual. The `DEMO' file included in the Hyperbole distribution demonstrates many of Hyperbole's standard facilities. It offers a much less technical introduction for Hyperbole users by providing good examples of how buttons may be used and an introduction to the outliner. So if this manual is too detailed for your taste, you can skip it entirely and just jump right into the demonstration, normally by typing {`C-h h d d'}, assuming Hyperbole has already been installed at your site. Otherwise, *note Initializing::., for Hyperbole installation and initialization information. Many users, however, will want to do more than browse with Hyperbole, e.g. create their own buttons. The standard Hyperbole button editing user interface is GNU Emacs-based, so a basic familiarity with the Emacs editing model is useful. The material covered in the GNU Emacs tutorial, normally bound to {`C-h t'} within Emacs, is more than sufficient as background. If some GNU Emacs terms are unfamiliar to you, *note Emacs Glossary: (emacs)Glossary.. Before we delve into Hyperbole, a number of acknowledgments are in order. Peter Wegner has encouraged the growth in this work. Morris Moore has helped me pursue my own research visions and keeps me striving for excellence. Doug Engelbart has shown me the bigger picture and continues to be an inspiration. His work provides a model from which I am beginning to draw. Kellie Clark and I jointly designed and implemented the Hyperbole outliner. * Menu: * Introduction:: * Button Concepts:: * Hyperbole Views:: * Using Hyperbole:: * Developing with Hyperbole:: * Glossary:: * Smart Key Reference:: * Outliner Keys:: * Suggestion or Bug Reporting:: * Questions and Answers:: * Ongoing Work:: * References:: * Key Binding Index:: * Code and File Index:: * Concept Index:: -- The Detailed Node Listing -- Introduction * Hyperbole Overview:: * Manual Overview:: Button Concepts * Explicit Buttons:: * Global Buttons:: * Implicit Buttons and Types:: * Action Types and Actions:: * Button and Type Precedences:: Using Hyperbole * Initializing:: * Smart Keys:: * Window Configurations:: * Operating Menus:: * Entering Arguments:: * Working with Explicit Buttons:: * Outliner:: * Rolodex:: Initializing * Internal Viewers:: * External Viewers:: * Link Variable Substitution:: * Button Colors:: Configuring Button Colors * Loading Hyperbole:: Working with Explicit Buttons * Creation:: * Renaming:: * Deletion:: * Modification:: * Location:: * Button Files:: * Buttons in Mail:: * Buttons in News:: Creation * Drags:: via Smart Mouse Key Drags * Menus:: via Hyperbole Menus Outliner Operation * Outliner Menu:: * Outliner History:: Rolodex Operation * Rolo Concepts:: * Rolo Menu:: * Rolo Keys:: * Rolo Settings:: Developing with Hyperbole * Hook Variables:: * Creating Types:: * Explicit Button Technicalities:: * Encapsulating Systems:: * Embedding Hyperbole:: Creating Types * Action Types:: * Implicit Button Types:: Explicit Button Technicalities * Button Label Normalization:: * Operational and Storage Formats:: * Programmatic Button Creation:: Smart Key Reference * Smart Mouse Keys:: * Smart Keyboard Keys:: File: hyperbole.info, Node: Introduction, Next: Button Concepts, Prev: Top, Up: Top Introduction ************ This chapter describes what Hyperbole is, lists some of its potential applications, and then summarizes the structure of the rest of the manual. * Menu: * Hyperbole Overview:: * Manual Overview:: File: hyperbole.info, Node: Hyperbole Overview, Next: Manual Overview, Prev: Introduction, Up: Introduction Hyperbole Overview ================== A Hyperbole user works with *buttons*; he may create, modify, move or delete buttons. Each button performs a specific action, such as linking to a file or executing a shell command. There are three categories of Hyperbole buttons: "explicit buttons" created by Hyperbole, accessible from within a single document; "global buttons" created by Hyperbole, accessible anywhere within a user's network of documents; "implicit buttons" created and managed by other programs or embedded within the structure of a document, accessible from within a single document. Hyperbole recognizes implicit buttons by contextual patterns given in their type specifications (explained later). Explicit Hyperbole buttons may be embedded within any type of text file. Implicit buttons may be recognized anywhere within a text file, depending on the implicit button types that are available. All global buttons are stored in a single location and activated by entering their names, rather than by direct selection, the means used to activate explicit and implicit buttons. To summarize: Button Category Active Within Activation Means Managed By ======================================================================== Explicit a single document direct selection Hyperbole Global any document specifying its name Hyperbole Implicit a matching context direct selection other tools ======================================================================== Hyperbole buttons may be clicked upon with a mouse to activate them or to describe their actions. Thus, a user can always check how a button will act before activating it. Buttons may also be activated from a keyboard. (In fact, virtually all Hyperbole operations, including menu usage, may be performed from any standard character terminal interface, so one need not be anchored to a workstation all day). *Note Smart Keys::. Hyperbole does not enforce any particular hypertext or information management model, but instead allows you to organize your information in large or small chunks as you see fit. The Hyperbole outliner organizes information hierarchies which may also contain links to external information sources. Some of Hyperbole's most important features include: * Buttons may link to information or may execute procedures, such as starting or communicating with external programs; * One simply drags between a button source location and a link destination to create or to modify a link button. The same result can be achieved from the keyboard. * Buttons may be embedded within electronic mail messages; * Outlines allow rapid browsing, editing and movement of chunks of information organized into trees (hierarchies); * Other hypertext and information retrieval systems may be encapsulated under a Hyperbole user interface (a number of samples are provided). Typical Hyperbole applications include: *personal information management* Overlapping link paths provide a variety of views into an information space. A search facility locates buttons in context and permits quick selection. *documentation and code browsing* Cross-references may be embedded within documentation. One can add a point-and-click interface to existing documentation, link code with associated design documents, or jump to the definition of an identifier by selecting its name within code or documentation. *brainstorming* The Hyperbole outliner, *Note Outliner::, is an effective tool for capturing ideas and then quickly reorganizing them in a meaningful way. Links to related ideas are easy to create, eliminating the need to copy and paste information into a single place. *help/training systems* Tutorials containing buttons can show students how things work while explaining the concepts, e.g. an introduction to local commands. This technique can be much more effective than written documentation alone. *archive managers* Programs that manage archives from incoming information streams may be supplemented by having them add topic-based buttons that link to the archive holdings. Users can then search and create their own links to archive entries. File: hyperbole.info, Node: Manual Overview, Prev: Hyperbole Overview, Up: Introduction Manual Overview =============== *Note Glossary::, provides definitions of Hyperbole terms for quick reference, so in some cases terms are not precisely defined within the text. Be sure to reference the glossary if a term is unclear to you. Although you need not have a keen understanding of all of these terms, a quick scan of the Glossary should help throughout Hyperbole use. *Note Button Concepts::, and *Note Hyperbole Views::, lay a conceptual foundation needed before the material in *Note Using Hyperbole::, can be utilized. *Note Smart Key Reference:: for reference documentation on the innovative, context-sensitive mouse and key handling offered by Hyperbole. *Note Questions and Answers:: for responses to a number of frequent questions. Developers comfortable with Emacs Lisp will want to continue on through *Note Developing with Hyperbole::. *Note Ongoing Work:: describes future directions in Hyperbole's evolution. File: hyperbole.info, Node: Button Concepts, Next: Hyperbole Views, Prev: Introduction, Up: Top Button Concepts *************** This chapter explains the user-level notion of Hyperbole buttons. You should read it before reading *Note Using Hyperbole::. Hyperbole buttons that are stored in files persist across Emacs sessions, so they provide a convenient means of linking from one information source to another. * Menu: * Explicit Buttons:: * Global Buttons:: * Implicit Buttons and Types:: * Action Types and Actions:: * Button and Type Precedences:: File: hyperbole.info, Node: Explicit Buttons, Next: Global Buttons, Prev: Button Concepts, Up: Button Concepts Explicit Buttons ================ Hyperbole creates and manages *explicit buttons* which look like this `<(fake button)>' to a Hyperbole user. They are quickly recognizable, yet relatively non-distracting as one scans the text in which they are embedded. The text between the `<(' and `)>' delimiters is called the "button label". Spacing between words within a button label is irrelevant to Hyperbole, so button labels may wrap across several lines without causing a problem. Hyperbole stores the "button data" that gives an explicit button its behavior, separately from the button label, in a file named `.hypb' within the same directory as the file in which the button is created. Thus, all files in the same directory share a common button data file. Button data is comprised of individual "button attribute" values. A user never sees this data in its raw form but may see a formatted version by asking for help on a button. Explicit buttons may be freely moved about within the buffer in which they are created. (No present support exists for moving buttons between buffers). A single button may also appear multiple times within the same buffer; one simply copies the button label with its delimiters to a new location in such cases. Each explicit button is assigned an action type which determines the actions that it performs. "Link action types" connect buttons to particular types of referents. "Activation" of such buttons then displays the referents. Hyperbole does not manage referent data; this is left to the applications that generate the data. This means that Hyperbole provides in-place linking and does not require reformatting of data to integrate it with a Hyperbole framework. File: hyperbole.info, Node: Global Buttons, Next: Implicit Buttons and Types, Prev: Explicit Buttons, Up: Button Concepts Global Buttons ============== Access to explicit buttons depends upon the information on your screen since they are embedded within particular buffers. Sometimes it is useful to activate buttons without regard to the information with which you are presently working. In such instances, you use "global buttons", which are simply explicit buttons which may be activated or otherwise operated upon by entering their labels when they are prompted for, rather than selecting the buttons within a buffer. If you want a permanent link to a file section that you can follow at any time, you can use a global button. Or what about an Emacs keyboard macro that you use frequently? Create an `exec-kbd-macro' button with an easy to type name and then you can easily activate it whenever the need arises. File: hyperbole.info, Node: Implicit Buttons and Types, Next: Action Types and Actions, Prev: Global Buttons, Up: Button Concepts Implicit Buttons and Types ========================== Implicit buttons are those defined by the natural structure of a document. They are identified by contextual patterns which limit the locations or states in which they can appear. Their behavior is determined by one or more actions which they trigger when activated. An action is derived from either a Hyperbole action type specification, *note Action Types and Actions::., or an Emacs Lisp function. Implicit button types may use the same action types that explicit buttons do. Implicit buttons never have any button data associated with them. They are recognized in context based on predicate matches defined within implicit button types. For example, Hyperbole recognizes file names enclosed in double quotes and can quickly display their associated files in response to simple mouse clicks. See `hibtypes.el' for complete examples. Standard implicit button types include (in alphabetical order): `annot-bib' Displays annotated bibliography entries referenced internally, delimeters = []. References must be delimited by square brackets, must begin with a word constituent character, and must not be in buffers whose names begin with a ' ' or '*' character. `completion' Inserts completion at point into minibuffer or other window. `dir-summary' Detects filename buttons in files named "MANIFEST" or "DIR". Displays selected files. Each file name must be at the beginning of the line and must be followed by one or more spaces and then another non-space, non-parenthesis, non-brace character. `doc-id' Displays an index entry for a site-specific document given its id. Ids must be delimited by 'doc-id-start' and 'doc-id-end' and must match the function given by 'doc-id-p'. This permits creation of catalogued online libraries. See `${hyperb:dir}/hib-doc-id.el' for more information. `elisp-compiler-msg' Jumps to source code for definition associated with byte-compiler error message. Works when activated anywhere within an error line. `debugger-source' Jumps to source line associated with debugger stack frame or breakpoint lines. This works with gdb, dbx, and xdb. Such lines are recognized in any buffer. `grep-msg' Jumps to line associated with grep or compilation error msgs. Messages are recognized in any buffer. `hyp-address' Turns a Hyperbole e-mail list address into an implicit button which inserts Hyperbole environment information. Useful when sending mail to a Hyperbole mail list. See also the documentation for `actypes::hyp-config'. `hyp-source' Turns source location entries in Hyperbole reports into buttons that jump to the associated location. `Info-node' Makes "(file)node" buttons display the associated Info node. `kbd-key' Executes a key sequence delimited by curly braces. Key sequences should be in human readable form, e.g. {`C-b'}. Forms such as {}, {}, and {^b} will not be recognized. `klink' Follows a link delimited by <> to a koutline cell. See documentation for `actypes::link-to-kotl' for valid link specifiers. `mail-address' If on an e-mail address in a specific buffer type, mail to that address in another window. Applies to the rolodex match buffer, any buffer attached to a file in ROLO-FILE-LIST, or any buffer with `mail' or `rolo' (case-insensitive) within its name. `man-apropos' `UNIX manual' `man pages' `man apropos' Makes man apropos entries display associated man pages when selected. `patch-msg' Jumps to source code associated with output from the `patch' program. Patch applies diffs to source code. `pathname' Makes a delimited, valid pathname display the path entry. Also works for delimited and non-delimited ange-ftp and efs pathnames. See `hpath:at-p' for possible delimiters. See `hpath:find' for special file display options. `rfc' Retrieves and displays an Internet rfc referenced at point. Requires ange-ftp or efs when needed for remote retrievals. The following formats are recognized: RFC822, rfc-822, and RFC 822. The HPATH:RFC variable specifies the location from which to retrieve RFCs." `rfc-toc' Summarizes contents of an Internet rfc from anywhere within rfc buffer. Each line in summary may be selected to jump to section. The Hyperbole Smart Keys offer extensive additional context-sensitive point-and-click type behavior beyond these standard implicit button types. *Note Smart Keys::. File: hyperbole.info, Node: Action Types and Actions, Next: Button and Type Precedences, Prev: Implicit Buttons and Types, Up: Button Concepts Action Types and Actions ======================== "Action types" provide action procedures that specify button behavior. The arguments needed by an action type are prompted for at button creation time. When a button is activated, the stored arguments are fed to the action type's "action" body to achieve the desired result. Hyperbole handles all of this transparently. Standard action types include: `annot-bib' Follows internal ref KEY within an annotated bibliography, delimiters=[]. `completion' Inserts completion at point into minibuffer or other window. Unless at end of buffer or if completion has already been inserted, then deletes completions window. `eval-elisp' Evaluates a Lisp expression LISP-EXPR. `exec-kbd-macro' Executes KBD-MACRO REPEAT-COUNT times. KBD-MACRO may be a string of editor command characters or a function symbol. Optional REPEAT-COUNT nil means execute once, zero means repeat until error. `exec-shell-cmd' Executes a SHELL-CMD string asynchronously. Optional non-nil second argument INTERNAL-CMD means do not display the shell command line executed. Optional non-nil third argument KILL-PREV means kill last output to shell buffer before executing SHELL-CMD. `exec-window-cmd' Executes an external window-based SHELL-CMD string asynchronously. `hyp-config' Inserts Hyperbole configuration info at end of optional OUT-BUF or current. `hyp-request' Inserts Hyperbole mail list request help into optional OUT-BUF or current. `hyp-source' Displays a buffer or file from a line beginning with 'hbut:source-prefix'. `kbd-key' Executes the function binding for KEY-SEQUENCE, delimited by {}. Returns t if a KEY-SEQUENCE has a binding, else nil. `link-to-buffer-tmp' Displays a BUFFER in another window. Link is generally only good for current Emacs session. Use 'link-to-file' instead for a permanent link. `link-to-directory' Displays a DIRECTORY in Dired mode in another window. `link-to-doc' Displays online version of a document given by DOC-ID, in other window. If the online version of a document is not found in DOC-ID-INDICES, an error is signalled. `link-to-ebut' Performs action given by another button, specified by KEY and KEY-FILE. `link-to-elisp-doc' Displays documentation for FUNC-SYMBOL. `link-to-file' Displays a PATH in another window scrolled to optional POINT. With POINT, buffer is displayed with POINT at the top of the window. `link-to-file-line' Displays a PATH in another window scrolled to LINE-NUM. `link-to-kcell' Displays FILE with kcell given by CELL-REF at the top of the window. CELL-REF may be a kcell's display label or its permanant idstamp. If FILE is nil, the current buffer is used. If CELL-REF is nil, the first cell in the view is shown. `link-to-kotl' Displays at the top of another window the referent pointed to by LINK. LINK may be of any of the following forms, with or without delimiters: < pathname [, cell-ref] > < [-!&] pathname > < @cell-ref > `link-to-Info-node' Displays an Info NODE in another window. NODE must be a string of the form '(file)nodename'. `link-to-mail' Displays mail msg with MAIL-MSG-ID from MAIL-FILE in other window. See documentation for the variable HMAIL:INIT-FUNCTION for information on how to specify a mail reader to use. `link-to-regexp-match' Finds REGEXP's Nth occurrence in FILE and displays location at window top. Returns t if found, signals an error if not. `link-to-rfc' Retrieves and displays an Internet rfc given by RFC-NUM. RFC-NUM may be a string or an integer. Requires ange-ftp or efs for remote retrievals. `link-to-string-match' Finds STRING's Nth occurrence in FILE and displays location at window top. Returns t if found, nil if not. `man-show' Displays man page on TOPIC, which may be of the form `<command>(<section>'). `rfc-toc' Computes and displays summary of an Internet rfc in BUF-NAME. Assumes point has already been moved to start of region to summarize. Optional OPOINT is point to return to in BUF-NAME after displaying summary. The use of action types provides a convenient way of specifying button behavior without the need to know how to program. Expert users who are familiar with Emacs Lisp, however, may find that they often want to tailor button actions in a variety of ways not easily captured within a type system. In such cases, HUI:EBUT-PROMPT-FOR-ACTION should be set non-nil. This will cause Hyperbole to prompt for an action to override the button's action type at each explicit button creation. For those cases where the action type is sufficient, a nil value should be entered for the action. An action may be any Lisp form that may be evaluated. File: hyperbole.info, Node: Button and Type Precedences, Prev: Action Types and Actions, Up: Button Concepts Button and Type Precedences =========================== Explicit buttons always take precedence over implicit buttons. Thus, if a button selection is made which falls within both an explicit and implicit button, only the explicit button will be selected. Explicit button labels are not allowed to overlap; Hyperbole's behavior in such cases is undefined. If there is no explicit button at point during a selection request, then each implicit button type predicate is tested in turn until one returns non-nil or all are exhausted. Since two implicit button types may have overlapping domains (those contexts in which their predicates are true), only the first matching type is used. The type predicates are tested in *reverse* order of definition, i.e. most recently entered types are tested first, so that personal types defined after standard system types take precedence. It is important to keep this order in mind when defining new implicit button types. By making their match predicates as specific as possible, one can minimize any overlapping of implicit button type domains. Once a type name is defined, its precedence relative to other types remains the same even if you redefine the body of the type, as long as you don't change its name. This allows incremental modifications to types without having to worry about shifts in type precedence. *Note Creating Types::, for information on how to develop or modify types. File: hyperbole.info, Node: Hyperbole Views, Next: Using Hyperbole, Prev: Button Concepts, Up: Top Hyperbole Views *************** This chapter explains the role of views in the display of information accessed via Hyperbole. You should read it before reading *Note Using Hyperbole::. This release of Hyperbole does not contain *any* support for views. A general view model is in development. The descriptions here are meant to familiarize you with the notion of views to be available in future releases. A "Hyperbole view" is a perspective on a pool of information. An outline of a document, a document extract, and a decrypted document all represent views of an original document (which may just be a file). "View specifications" or view specs, for short, control the application of views to displayed information. An action type which displays a buffer of text, the "result buffer", can apply a view spec to the buffer before display. A user can then manipulate the view by interactively altering the view spec associated with the buffer. A 'V' in an action type's interactive call string indicates that the view spec of any button which uses the action type should be applied to the result buffer of the action type. File: hyperbole.info, Node: Using Hyperbole, Next: Developing with Hyperbole, Prev: Hyperbole Views, Up: Top Using Hyperbole *************** This chapter covers user interaction with Hyperbole. Often a number of overlapping interaction methods are provided to support different work styles and hardware limitations. You need learn only one with which you can become comfortable, in such instances. Remember that the `DEMO' file included in the Hyperbole distribution demonstrates many of Hyperbole's standard facilities, *Note Preface: Top, for more details. * Menu: * Initializing:: * Smart Keys:: * Window Configurations:: * Operating Menus:: * Entering Arguments:: * Working with Explicit Buttons:: * Outliner:: * Rolodex:: File: hyperbole.info, Node: Initializing, Next: Smart Keys, Prev: Using Hyperbole, Up: Using Hyperbole Initializing ============ Hyperbole must be installed at your site before you can use it. The `README' file that comes with the Hyperbole distribution explains how to install it and how to join the Hyperbole interest mail lists. See the Msg/ menu item in *Note Operating Menus::, for a convenient means of joining and mailing to these lists. If you are installing Hyperbole at your site, please read the `README' file before continuing in this document. If you want to customize the basic Hyperbole initialization sequence for yourself rather than the users at your site, you should make a personal copy of the `hsite.el' file, modify it the way you want, and then load it. (If you are familiar with Emacs Lisp, see also *Note Hook Variables::.) * Menu: * Internal Viewers:: * External Viewers:: * Link Variable Substitution:: * Button Colors:: Configuring Button Colors * Loading Hyperbole:: File: hyperbole.info, Node: Internal Viewers, Next: External Viewers, Prev: Initializing, Up: Initializing Internal Viewers ---------------- When given a file name, Hyperbole will by default display the file for editing within an Emacs buffer. The HPATH:DISPLAY-ALIST variable can be used to specify file name patterns, such as matching suffixes, which will invoke a special Emacs Lisp function to display any matching files within Emacs. This can be used to format raw data files for convenient display. Configure the HPATH:DISPLAY-ALIST variable in `hsite.el'. Its value is an association list whose elements are (<file-name-regular-expression> . <function-of-one-arg>) pairs. Any path whose name matches a <file-name-regular-expression> will be displayed by calling the associated <function-of-one-arg> with the file name as the argument. *Note External Viewers::, for instructions on associating file names with external, window-system specific viewers. File: hyperbole.info, Node: External Viewers, Next: Link Variable Substitution, Prev: Internal Viewers, Up: Initializing External Viewers ---------------- If you will be using Hyperbole under a window system, you may want to configure the HPATH:FIND-ALIST variable in `hsite.el' to support hyperlinks which open files using non-Emacs tools, e.g. a fax reader or a bitmap viewer. The value of HPATH:FIND-ALIST is determined when Hyperbole is initialized based upon the current window system and the version of Emacs in use. The value is an association list whose elements are (<file-name-regular-expression> . <viewer-program>) pairs. Any path whose name matches a <file-name-regular-expression> will be displayed using the corresponding viewer-program. If a <viewer-program> entry contains a `%s' string, the filename to display will be substituted at that point within the string. Otherwise, the filename will be appended to the <viewer-program> entry. See the "x-suffixes" and "nextstep-suffixes" settings within the definition of HPATH:FIND-ALIST as examples. File: hyperbole.info, Node: Link Variable Substitution, Next: Button Colors, Prev: External Viewers, Up: Initializing Link Variable Substitution -------------------------- Another variable to consider modifying in the `hsite.el' file is HPATH:VARIABLES. This variable consists of a list of Emacs Lisp variable names, each of which may have a pathname or a list of pathnames as a value. Whenever a Hyperbole file or directory link button is created, its pathname is compared against the values in HPATH:VARIABLES. The first match found, if any, is selected and its associated variable name is substituted into the link pathname, in place of its literal value. When the link is resolved (the button is activated), Hyperbole replaces each variable with the first matching value from this list. (Environment variables are also replaced whenever link paths are resolved. This permits sharing of links over wide areas, where the variable values may differ between link creator and link activator. The entire process is wholly transparent to the user; it is explained here simply to help you in deciding whether or not to modify the value of HPATH:VARIABLES. File: hyperbole.info, Node: Button Colors, Next: Loading Hyperbole, Prev: Link Variable Substitution, Up: Initializing Configuring Button Colors ------------------------- When Hyperbole is run under a window system together with Emacs 19, XEmacs or Epoch, it can automatically highlight any explicit buttons in a buffer and make them flash when selected. The only configuration necessary is selection of a color (or style) for button highlighting and button flashing. See the `hui-*-b*.el' files for lists of potential colors and the code which supports this behavior. A call to `(hproperty:cycle-but-color)' within a Hyperbole initialization sequence changes the color used to highlight and flash explicit buttons. Additionally, under XEmacs, if HPROPERTY:BUT-EMPHASIZE-P is set to `t' in `hsite.el', then whenever the mouse pointer moves over an explicit button, it will be emphasized in a different color or style. This emphasis is in addition to any non-mouse-sensitive button highlighting. File: hyperbole.info, Node: Loading Hyperbole, Prev: Button Colors, Up: Initializing Loading Hyperbole ----------------- Each time you start a new Emacs session, the Hyperbole code must be loaded for you to use it. The easiest way to achieve this is to add two lines to your `~/.emacs' file, which Emacs reads automatically on startup. The lines should be: (load "<HYP-DIR>/hversion") (load "<HYP-DIR>/hyperbole") where the local Hyperbole installation directory is substituted for `<HYP-DIR>'. This establishes a few key bindings and sets up Hyperbole to automatically load whenever you activate its menu. If you would rather have the whole Hyperbole system loaded when you start up so that you can always use the Smart Keys and other facilities, add a third line after the above two lines. (require 'hsite) If you use mouse keys, be sure to add the above lines after any setup of mouse key bindings, to ensure that Hyperbole's mouse keys are initialized. *Note Smart Keys::, for further details. If you use any Hyperbole mail or news support, *note Buttons in Mail::., be certain to perform all of your personal mail/news initializations before the point at which you load Hyperbole. Otherwise, the mail/news support may not be configured properly. For example, if you use the Emacs add-on Supercite package, its setup should come before Hyperbole initialization. File: hyperbole.info, Node: Smart Keys, Next: Window Configurations, Prev: Initializing, Up: Using Hyperbole Smart Keys ========== Hyperbole provides two special "Smart Keys" that perform context-sensitive operations, the Action Key and the Assist Key. By default, the "Action Key" is bound to your shift-middle mouse button (or shift-left on a 2-button mouse) and the "Assist Key" is bound to your shift-right mouse button, assuming Hyperbole is run under an external window system. (InfoDock users should use the middle mouse button as the Action Key, instead.) Mouse configuration is automatic for XEmacs and Epoch under the X window system and for GNU Emacs versions 18 and 19 under X, OpenWindows, NEXTSTEP, SunView and Apollo's Display Manager, assuming your Emacs program has been built with support for any of these window systems. By default (if HKEY-INIT is left with a setting of `t' in `hsite.el'), then {`M-RET'} may also be used as the Action Key and {`C-u M-RET'} may be used as the Assist Key. In many read-only modes like Dired and Rmail, {RTN} also functions as the Action Key. These key bindings allow context sensitive operation from any keyboard. If you prefer other key bindings, simply bind the commands `action-key' and `assist-key' to keyboard keys. `hkey-either' may be used instead if you prefer a single key binding for both commands; a prefix argument then invokes `assist-key'. You may also bind `action-mouse-key' and `assist-mouse-key' to mouse keys, as you like. The Action Key generally selects entities, creates links and activates buttons. The Assist Key generally provides help, such as reporting on a button's attributes, or serves a complementary function to whatever the Action Key does within a context. You can get a summary of what the Smart Keys do in all of their different contexts by pressing the Assist Key in the right corner (within the rightmost 3 characters) of a window modeline or by using the Hyperbole Doc/SmartKy menu entry. The following table is an example of this summary. Much of the browsing power of Hyperbole comes from use of the Smart Keys, so you should spend some time practicing how to use them. This table may appear daunting at first, but as you practice and notice that the Smart Keys do just a few context-sensitive things per editor mode, you will find it easy to just point and click and let Hyperbole do the rest. For extensive reference documentation on the Smart Keys, *note Smart Key Reference::.. ============================================================================== Smart Keys Context Action Key Assist Key ============================================================================== Hyperbole On a menu item Item is activated Item help On an explicit button Button is activated Button help Reading argument 1st press at an arg value Value copied to minibuffer <- same 2nd press at an arg value Value used as argument <- same In minibuffer Minibuf arg is applied Completion help On an implicit button Button is activated Button help Within an outline cell Collapses and expands Shows tree props Left of an outline cell Creates a klink Moves a tree Wrolo Match Buffer Edits entries and mails to e-mail addresses Mouse or Keyboard Display Control Line end, not end of buffer smart-scroll-proportional = nil (default) Scrolls up a windowful Scrolls down = t Makes curr line top line Bottom line End of Any Help buffer Screen restored to previous state Mouse-only Control Modeline down & wind release Resize window height <- same Drag from shared window side or from left of scroll bar Resize window width <- same Drag between windows Create/modify a link but Swap window buffers Horizontal drag within window Left to right Scroll to buffer end Split window across Right to left Scroll to buffer begin Delete window Vertical drag within window Split window sideways <- same Diagonal drag within window Save ring screen-config Restore ring config Click in modeline Left window edge Bury buffer Unbury bottom buf Right window edge Info Smart Key summary Otherwise Action Key Hook Assist Key Hook Special Modes C/C++ Mode Jumps to id/include def Jumps to next def Assembly Language Mode Jumps to id/include def Jumps to next def Any Lisp mode Jumps to id def Jumps to next def Emacs Lisp Compiler Error Jumps to def with error <- same Grep or Occur match Jumps to match source line <- same Multi-buffer occur match Jumps to match source line <- same Outline Major/Minor Modes Collapses, expands, and moves outline entries Man Apropos Displays man page entry <- same Man Pages Follows cross refs, file refs and C code refs Buffer Menu Saves, deletes and displays buffers Emacs Info Reader Menu Entry or Cross Ref Jumps to referent <- same Up, Next or Prev Header Jumps to referent Jumps to prior node File entry of Header Jumps to top node Jumps to (DIR) node End of current node Jumps to next node Jumps to prev node Anywhere else Scrolls up a windowful Scrolls down a wind Subsystems Calendar Scrolls or shows appts Scrolls/marks dates Dired Mode Views and deletes files from directory listing GNUS News Reader Toggles group subscriptions, gets new news, and browses articles Mail reader and Summaries Browses, deletes and expunges messages OO-Browser Browses classes and elements Tar Mode Views and edits files from tar archive files Any other context (defaults) Hyperbole top menu Smart Key summary ============================================================================== Note how the last line in the table explains the default behavior of the Smart Keys. That is what they do when they cannot find a context match at your current location. See the documentation for the variables ACTION-KEY-DEFAULT-FUNCTION and ASSIST-KEY-DEFAULT-FUNCTION for information on how to customize the behavior of the Smart Keys within default contexts. A prime design criterion of Hyperbole's user interface is that one should be able to see what an operation will do before using it. The Assist Key provides help for button and menu item actions. Hyperbole also shows the result of directly selecting an argument value, to provide feedback as to whether the right item has been selected. When you use a mouse and you want to find out what either of the Smart Keys does within a context, depress the one you want to check on and hold it down, then press the other and release as you please. A help buffer will pop up explaining the actions that will be performed in that context, if any. A press of either Smart Key at the end of that help buffer will restore your display to its configuration prior to invoking help. By default (if HKEY-INIT is left set equal to `t' in `hsite.el'), then {`C-h A'} will display this same context-sensitive help for the Action Key while {`C-u C-h A'} will display the help for the Assist Key. Note that {`C-h a'} will perform a function unrelated to Hyperbole, so you must press the shift key when you hit the `A' character. When Hyperbole is installed, a key may be bound which allows you to switch between the Smart Key mouse bindings and your prior ones. `C-h w hmouse-toggle-bindings RTN' should show you any key which performs this command. If no key binding has been established or if you prefer one of your own, simply select a key and bind it within your `~/.emacs' file. For example, `(global-set-key "\C-ct" 'hmouse-toggle-bindings)'. File: hyperbole.info, Node: Window Configurations, Next: Operating Menus, Prev: Smart Keys, Up: Using Hyperbole Window Configurations ===================== Hyperbole includes the `wconfig.el' package which lets you save and restore window configurations, i.e. the window layout and buffers displayed within an Emacs frame. This is useful to save a particular working context and then to jump back to it at a later time during an Emacs session. It is also useful during demonstrations to pull up many informational artifacts all at once, e.g. all of the windows for a particular subsystem. None of this information is stored between Emacs sessions, so your window configurations will last only through a single session of use. The wconfig library provides two distinct means of managing window configurations. The first means associates a name with each stored window configuration. The name can then be used to retrieve the window configuration later. The second means uses a ring structure to save window configurations and then allows browsing through the sequence of saved configurations. The Win/ menu entry on the Hyperbole top-level menu displays a menu of window configuration commands: WinConfig> AddName DeleteName RestoreName PopRing SaveRing YankRing Menu Item Command Description ==================================================================== AddName wconfig-add-by-name Name current wconfig DeleteName wconfig-delete-by-name Delete wconfig with name RestoreName wconfig-restore-by-name Restore wconfig by name PopRing wconfig-delete-pop Restore and delete wconfig SaveRing wconfig-ring-save Store wconfig to ring YankRing wconfig-yank-pop Restore next wconfig ==================================================================== Saving and restoring window configurations by name is the easiest method, but it requires that you input the chosen name from the keyboard. The ring commands permit saving and restoring through mouse interaction only, if so desired. The prior section, *note Smart Keys::., mentions how to save and restore window configurations with the Smart Keys. Since the ring commands are a bit more complex than their by-name counterparts, the following paragraphs explain them in more detail. Wconfig creates a ring structure that operates just like the Emacs KILL-RING, *note Kill Ring: (emacs)Kill Ring., but its elements are window configurations rather than text regions. One can add an element to the ring based upon the current window configuration. After several elements are in the ring, one can walk through all of them in sequence until the desired configuration is restored. SaveRing executes the `wconfig-ring-save' command which saves the current window configuration to the ring. YankRing executes the `wconfig-yank-pop' command. It restores the window configuration from the currently pointed to configuration in the ring. It does not delete this configuration from the ring but it does move the pointer to the prior ring element. Repeated calls to this command thus restore successive window configurations until the ring pointer wraps around. Simply stop when a desired configuration appears. PopRing calls the `wconfig-delete-pop' command. It is used to restore a previously saved configuration and at the same time delete it from the ring. The maximum number of elements the ring can hold is set by the WCONFIG-RING-MAX variable whose default is 10. Any saves beyond this value cause deletion of the oldest element in the ring before a new one is added.